   This file documents the Elisp package `hm--html-menus'.

   Copyright (C) 1997 Heiko Münkel

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Distribution" and "General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "Distribution" and "General
Public License" may be included in a translation approved by the author
instead of in the original English.

Defining The Drag And Drop Actions
----------------------------------

   The drag and drop actions are commands which are called after an
internal drag and drop. They depend on the source and the destination
of the drag and drop. Drag and drop actions are defined by the variable:

   * `idd-actions': A list with actions, depending on the source and the
     destination of the drag and drop command.

   The list looks like:
     '((<DESTINATION-SPECIFICATION-1> (<SOURCE-SPECIFICATION-1> <ACTION-1-1>)
                                 (<SOURCE-SPECIFICATION-2> <ACTION-1-2>)
                                                 :
        )
       (<DESTINATION-SPECIFICATION-2> (<SOURCE-SPECIFICATION-1> <ACTION-2-1>)
                                 (<SOURCE-SPECIFICATION-2> <ACTION-2-2>)
                                                 :
        )
                               :
       )
   The <SOURCE-SPECIFICATION> looks like the following:
     '([(<SPECIFICATION-TYPE> <VALUE>)])
   with
    <SPECIFICATION-TYPE> :==
          `idd-if-minor-mode-p' | `idd-if-buffer-name-p' |
          `idd-if-region-active-p' | `idd-if-url-at-point-p' |
          `idd-if-major-mode-p' | `idd-if-variable-non-nil-p' |
          `idd-if-dired-file-on-line-p' |
          `idd-if-dired-no-file-on-line-p' | `idd-if-local-file-p' |
          `idd-if-buffer-name-p' | `idd-if-modifiers-p' | ...

   The <SPECIFICATION-TYPE> - functions must have two arguments. The
first one is the source or destination and the second is the <VALUE>.
It must return `nil', if the test wasn't successful, and a number (in
general 1), which specifies the weight of the test function. The
weights of all single tests are added to a summary weight and assigned
to the action. The action with the highest weight is called from the
action handler. Look at the definition of `idd-if-major-mode-p',
`idd-if-minor-mode-p' and so on for examples. Look at the function
`idd-get-source-or-destination-alist', if you want to know the
structure of the `source-or-destination' argument of these functions.

   The <DESTINATION-SPECIFICATION> looks like <SOURCE-SPECIFICATION>,
but in general it could be set to `nil' in mode specific idd-action
lists.

   If <DESTINATION-SPECIFICATION-1> or <SOURCE-SPECIFICATION-1> is set
to `nil', then every source or source matches. `idd-actions' is a
buffer local variable, which should be at least mode depended. So if
the <DESTINATION-SPECIFICATION-1> is set to `nil' it says, that the
destination buffer must only have a specific mode. However, it's also
possible to define a general `idd-actions' list, where the destination
mode is specified by `idd-if-major-mode-p'.

   <ACTION> is a function which has two arguments. The first specifies
the source and the second the destination. Look at the function
definition of `idd-action-copy-region' and
`idd-action-copy-replace-region'. They are examples for such actions.

   The following is an example for `hm--html-mode':

     (defvar idd-actions
       '((nil (((idd-if-major-mode-p . dired-mode)
                (idd-if-dired-file-on-line-p . ".*\\.\\(gif\\)\\|\\(jpq\\)"))
               hm--html-idd-add-include-image-from-dired-line)
              (((idd-if-major-mode-p . dired-mode)
                (idd-if-dired-no-file-on-line-p . nil))
               hm--html-idd-add-file-link-to-file-on-dired-line)
              (((idd-if-major-mode-p . dired-mode)
                (idd-if-dired-no-file-on-line-p . t))
               hm--html-idd-add-file-link-to-directory-of-buffer)
              (((idd-if-major-mode-p . w3-mode)
                (idd-if-url-at-point-p . t))
               hm--html-idd-add-html-link-from-w3-buffer-point)
              (((idd-if-major-mode-p . w3-mode))
               hm--html-idd-add-html-link-to-w3-buffer)
              (((idd-if-local-file-p . t))
               hm--html-idd-add-file-link-to-buffer)))

The Mouse Bindings
------------------

   The following three variables determine the mouse bindings and the
mouse behaviour for the internal drag and drop package:

   * `idd-global-mouse-keys': The mouse keys for the command
     `idd-mouse-drag-and-drop'.  The command `idd-mouse-drag-and-drop'
     is bound during the loading of the package
     `internal-drag-and-drop' to these keys in the global keymap. The
     drag and drop action must be bound global, because the drag and
     drop action must be started by a click in the source buffer.
     Therefore no action will be performed if the mouse keys are not
     bound to `idd-mouse-drag-and-drop' in the destination buffer.

     Set it to `nil', if you don't want to bind this function during
     loading.

     If the command is already bound in the global keymap during
     loading, then this key sequence will not be bound.

     By default the mouse binding is <meta> <control> <button1>.

   * `idd-global-help-mouse-keys': The mouse keys for the command
     `idd-help-mouse-drag-and-drop'.  The command
     `idd-help-mouse-drag-and-drop' is bound during the loading of the
     package `internal-drag-and-drop' to these keys in the global
     keymap.

     Set it to `nil' if you don't want to bind this function during
     loading.

     If the command is already bound in the global keymap during
     loading, then this key sequence will not be bound.

     By default the mouse binding is <meta> <control> <button3>.

   * `idd-drag-and-drop-mouse-binding-type': The type of the drag and
     drop mouse binding.  The value may be `click' or
     `press-button-during-move'.  A value of `click' means that you
     have to click over the source, release the button and click it
     again over the destination.  A value of `press-button-during-move'
     means that you have to press the button down over the source and
     hold it until the mouse pointer is over the destination.

     The *disadvantage* of the `press-button-during-move' type compared
     with the `click' type is that you can't select a destination
     region, and therefore a drag and drop action depending on a
     selected region can't be started with that type of mouse binding.

The Drag And Drop Mouse Pointer
-------------------------------

   In the XEmacs the mouse pointer glyph (shape) can be set to any
glyph. This is used during the drag and drop command to indicate, that
the command is active. There exists the following three variables to
customize this:

   * `idd-mouse-pointer-image': The name of the xbm file with the mouse
     pointer image. By default this is the file `drop'. There exists
     also a file called `dropmsk', which contains the mask image. The
     mask file is loaded automaticly.

   * `idd-data-directory': The name fo the directory, where the file
     `idd-mouse-pointer-image' is searched. By default this is the
     subdirectory `idd' in the XEmacs install directory
     `data-directory'.

   * `idd-overwrite-mouse-pointers': A list with pointer glyph
     variables, which should be overwritten by the
     `idd-drag-and-drop-pointer-glyph'. If it is nil, the pointer wont
     be changed. Currently it must be nil in the Emacs.

   If one of the variables `idd-mouse-pointer-image' or
`idd-data-directory' is changed, the command
`idd-make-drag-and-drop-pointer-glyph' must be called. This command
builds the mouse pointer glyph, which is stored in
`idd-drag-and-drop-pointer-glyph'.

   I don't know how to set the the mouse pointer in the Emacs to a drag
and drop image. Any hints for doing this are welcome.

The Drag And Drop Commands
==========================

   There are 2 groups of commands. The first contains commands which
perform the drag and drop action and the second displays help messages
about a possible drag and drop action.

Performing The Drag And Drop Action
-----------------------------------

   The following five commands perform internal drag and drop actions:

   * `idd-mouse-drag-and-drop': Performs a drag and drop action.  It
     calls the command `idd-mouse-drag-and-drop-click' or
     `idd-mouse-drag-and-drop-press-button-during-move' depending on the
     value of `idd-drag-and-drop-mouse-binding-type'. However you've set
     this, you start a drag and drop action with this command by
     pressing down its mouse button over the source. This command is
     bound by default to a global mouse key sequence. See The Mouse Bindings.

   * `idd-start-mouse-drag-and-drop': Starts a drag and drop command.
     This command could be used to start a drag and drop command
     without a button event. Therefore this should not be bound
     directly to a mouse button. This command can be used to start a
     drag and drop action with a click on a menu item or tool bar icon.
     After that you have to press a mouse button over the source. The
     rest depends on the value of
     `idd-drag-and-drop-mouse-binding-type', as with the command
     `idd-mouse-drag-and-drop'.

   * `idd-help-start-action': It is possible to display a help buffer
     with a message in it, which describes the action instead of
     performing it immediately (see Displaying Help On Drag And Drop.).
     In this case you can perform the action by clicking on a
     special extent in the help buffer, which runs this command.

   * `idd-mouse-drag-and-drop-press-button-during-move': Performs a drag
     and drop action in a more traditional way than
     `idd-mouse-drag-and-drop-click'. First you press the button over
     the source and then move with the depressed button to the
     destination, where you release the button.  This must be bound to a
     mouse button. The `SOURCE-EVENT' must be a `button-press-event'.

     The disadvantage of this command compared with the command
     `idd-mouse-drag-and-drop-click' is, that you can't select a
     destination region.

     You should bind the command `idd-mouse-drag-and-drop' instead of
     this one, because it's then possible to switch between both drag
     and drop behaviours by changing only one variable.

   * `idd-mouse-drag-and-drop-click': Performs a drag and drop action in
     a more useful way than
     `idd-mouse-drag-and-drop-press-button-during-move'. First you
     click on the source and then on the destination.  This must be
     bound to a mouse button. The `SOURCE-EVENT' must be a
     `button-press-event'.

     You should bind the command `idd-mouse-drag-and-drop' instead of
     this one, because it's then possible to switch between both drag
     and drop behaviours by changing only one variable.

Displaying Help On Drag And Drop
--------------------------------

   It's possible to display a buffer with a help message describing the
action being considered before actually performing it. To perform the
action, you then click on a special extent in the help buffer. To get
the help buffer, you do the same things as you do to perform the action
itself. Only the mouse key differs. There are two commands for this:

   * `idd-help-mouse-drag-and-drop': Displays help about the drag and
     drop action. It works similarly to `idd-mouse-drag-and-drop'
     (see Performing The Drag And Drop Action.).

     By default this command is globally bound to <meta> <control>
     <button3>. This may be changed with the variable
     `idd-global-help-mouse-keys' (see The Mouse Bindings.).

   * `idd-start-help-mouse-drag-and-drop': Starts displaying help about
     the drag and drop action. It works similarly to
     `idd-start-mouse-drag-and-drop' (see Performing The Drag And Drop Action.)
     and can be used to start the help by clicking on a
     menu item or a tool bar icon.

Template Minor Mode
*******************

   There's a file called `tmpl-minor-mode.el' in the distribution of
the package *hm--html-menus*. It provides functions to use templates
for the `hm--html-mode' and also for other modes. It needs nothing from
the rest of the package and therefore it can be used independently of
`hm--html-mode'.

What Are Templates
==================

   Templates are special pieces of text, which can be expanded by
emacs. Expansion means that the template is replaced by something else,
determined by evaluating lisp forms or emacs commands.  The expansion
can be done automatically after the insertion of templates with the
command `tmpl-insert-template-file' in a buffer or by hand with the
commands `tmpl-expand-templates-in-buffer' or
`tmpl-expand-templates-in-region'.

   Templates can be put together with normal text in a so called
template file to provide prototype files. You should name these files
with the following naming scheme:

             <FILE>.<TYPE>.tmpl

   where <FILE> is a string which describes for what the template could
be used and <TYPE> the normal file extension, e.g. `c' for C- files or
`html' for HTML- files.

Syntax Of Templates
===================

   The templates are marked with the sign ^@, which stands for the null
character (\000). It can be inserted in a buffer with the keys `C-q
C-SPC'. You can also use any other character or string of characters by
changing the variable `tmpl-sign'.

   At the moment, there are 3 major types of templates:

  1. *Emacs Lisp function templates*: The expansion of such a template
     evals a lisp form. It is possible to use functions or variables as
     lisp forms. The following is a simple example:

          ^@LISP^@ (insert-file "~/.emacs") ^@END LISP^@

     inserts the contents of the file `~/.emacs' in the current buffer
     during the expansion.

  2. *Emacs command templates*: The expansion of a command template
     evals a template in the same way as an interactive command, which
     is invoked with `M-x command'. For example:

          ^@COMMAND^@ insert-file ^@END COMMAND^@

     runs the interactive command `insert-file' during the expansion.

  3. *Template comments* Nothing will be evaluated during the expansion
     of a template comment. It is only a comment. For example:

          ^@C^@ This is a comment

     The end of the comment is the end of the line. Therefore it has
     the same syntax as a lisp or C++ comment.

   By default, a template will be deleted after its expansion, but
without the linefeed. Look at the following examples:

   Before the expansion:

     	Line before the template
             ^@C^@ The Text of a comment template
     	Line after the template

   After the expansion:

   	Line before the template

   	Line after the template

   Templates can start in any column, and only the template will be
deleted after its expansion.

   It is also possible to put an attribute list in a template. The
attributes of the list control the deletion of the template. It may be
that this will be extended in the future with other attributes.  The
attribute list must be specified as an alist (assoc list) in the start
tag of a template and after its type. Each element of the alist consists
of the name of the attribute following its value.  If no attribute list
is specified or if an attribute is missing, then the default values are
used. At the moment there are the following 2 attributes:

  1. *don't delete attribute* (`DONT_DELETE'): If the value is t, then
     the template will not be deleted after its expansion. If the value
     is nil then the template will be deleted. The default is nil. For
     example:

     Before the expansion:

          	Line before the template
          	^@LISP ((DONT-DELETE t))^@ (insert-file "~/.cshrc") ^@END LISP^@
          	Line after the template

     After the expansion:

          	Line before the template
          	^@LISP ((DONT-DELETE t))^@ (insert-file "~/.cshrc") ^@END LISP^@
          	Line after the template

     It was assumed, that the file `~/.cshrc' was empty !

  2. *delete line attribute* (`DELETE-LINE'): If the value is t, then
     the linefeed before or after the template will be deleted. If the
     value is nil then no linefeed will be deleted. The default is nil.
     For example:

     Before the expansion:

          	Line before the template
          	^@LISP ((DELETE-LINE t))^@ (insert-file "~/.cshrc") ^@END LISP^@
          	Line after the template

     After the expansion:

          	Line before the template
          	Line after the template

     It was assumed, that the file `~/.cshrc' was empty !

   These attributes can be combined. For example:

     	^@COMMAND ((DELETE-LINE t) (DONT-DELETE nil))^@
     	insert-file
     	^@END COMMAND^@

   The last examples show also that whitespace (blanks, tabs, linefeeds)
is allowed at most positions in a template.

   Look at the file `tmpl-minor-mode.el' for a description of the
commands to expand templates.

Template Customization
======================

   Since the XEmacs 19.15 and 20.2 a special package can be used for the
customization of lisp packages. The internal drag and drop package uses
now also this feature. Therefore you can set all user variables with the
help of the Customize submenu, which can be selected in the Option menu.
If you use it, the variables will currently be saved in a special
customization file. Please look at the `NEWS' file or the info manuals
of the XEmacs to find out more about the customization package.

   Templates may be used for all editing modes, not only for
`hm--html-mode'. Therefore their general customization isn't done in
`hm--html-configuration.el'. Template variables are defined in the file
`tmpl-minor-mode.el' instead. You can set them in your `.emacs' or in
one of the other emacs init files (e.g.  `default.el'). The following
are the main variables for customization.

   * `tmpl-template-dir-list': A list of directories with template
     files. If it is nil, the default-directory will be used.  If more
     than one directory is specified, then the template filenames
     should differ in all directories.

     This variable is used in the commands for inserting templates.
     Look at `tmpl-insert-template-file-from-fixed-dirs' and at
     `tmpl-insert-template-file'. The command
     `tmpl-insert-template-file' uses only the car of the list (if it is
     a list.)

   * `tmpl-filter-regexp': This defines a regular expression used for
     filtering out non-template files in template directories. It is
     used in the command `tmpl-insert-template-file-from-fixed-dirs' to
     allow only the selection of files which match the regexp.  If it is
     nil, then the Filter `".*\\.tmpl$"' is used.  Set it to `\".*\"'
     if you want to disable the filter function or use the command
     `tmpl-insert-template-file'.

   * `tmpl-automatic-expand': If you insert a template file with
     `tmpl-insert-template-file-from-fixed-dirs' or with
     `tmpl-insert-template-file', this variable is used. The templates
     in the buffer will be automatically expanded if the variable is
     set to t, which is the default.

   * `tmpl-sign': Thisdetermines the sign which marks the beginning and
     the end of template expressions. By default it is set to the null
     character (displayed in emacs as ^@). You can also set this to a
     string. Be careful if you change it, so that the templates will
     not be mixed up with other non-template text! Note: The expansion
     function looks at the whole template, so that it is very unlikely
     that the function will make a mistake.

   * `tmpl-minor-mode-map': The keymap for the template minor mode.

Template Commands
=================

   In this section the commands of the template package are described.

Insert Of Template Files
------------------------

   The template package provides the following two commands for
inserting template files in an emacs buffer.

   * `tmpl-insert-template-file': This command can be used to insert a
     template file in the current buffer. It will expand the templates
     in the buffer if `tmpl-automatic-expand' is set to `t'. You can set
     a default directory for this command by setting the variable
     `tmpl-template-dir-list'. See Template Customization.

   * `tmpl-insert-template-file-from-fixed-dirs': The difference from
     the simpler command `tmpl-insert-template-file' is that this
     command will build a list for filename completion from a list of
     predefined directories (look at `tmpl-template-dir-list'). The
     filename completion list will also be filtered with the regular
     expression defined by `tmpl-filer-regexp'. See Template Customization.
     You can set the directory list and/or the filter
     differently in each mode where you use templates, so that you will
     get in the completion list only template files which could be used
     for the current mode.

     If you want to insert a template file with this command, which is
     not in one of the directories from `tmpl-template-dir-list', then
     you have to enter the string *"Change the directory"* instead of a
     template file. This string is also in the completion list.

   Both commands can also be used as functions. In this case the
template file with is directory path must be given to them as an
parameter.

   You can also use commands like `insert-file' to insert template
files and expand them by hand (see Expansion Of Templates.).

Expansion Of Templates
----------------------

   You can expand templates by hand or automatically after their
insertion. See Insert Of Template Files, for automatic expansion.
Expansion by hand can be done with one of the following two functions:

   * `tmpl-expand-templates-in-region': Expands the templates in the
     region. The region is established by the optional arguments `BEGIN'
     and `END'. If the arguments are `nil', or if the function is called
     interactively, then the current region will be used.

   * `tmpl-expand-templates-in-buffer': Expands all templates in the
     current buffer.

   Both commands are bound to keys in the `tmpl-minor-mode'. See The Template Minor Mode.

Escaping Of Template Signs
--------------------------

   It is possible to escape template signs in a buffer or in a region.
Templates with escaped template signs are not expanded, but they are
un-escaped by the expansion functions. Therefore it is possible to
exclude single templates from the expansion by escaping them. Note: You
can't escape a template twice. The commands which can be used for this
are:

   * `tmpl-escape-tmpl-sign-in-region': Escapes all `tmpl-sign's (see
     Template Customization.) with a `tmpl-sign' in a region. The
     region is established by the optional arguments `BEGIN' and `END'.
     If the arguments are `nil', or if the function is called
     interactively, then the current region will be used.

   * `tmpl-escape-tmpl-sign-in-buffer': Same as
     `tmpl-escape-tmpl-sign-in-region', but escapes all templates in the
     whole buffer.

   Both commands are bound to keys in `tmpl-minor-mode'. See The Template Minor Mode.

The Template Minor Mode
-----------------------

   The template minor mode can be toggled with the command
`tmpl-minor-mode'. The purpose of this mode is only to provide key
bindings for some of the commands of the package `tmpl-minor-mode'. If
you don't want to use the key bindings, you don't need this minor mode.

   Look at the key table `tmpl-minor-mode-map' (see Template Customization.)
for the definition of the keys.

   It may be that I'll also provide a pulldown or popup menu for the
minor mode in a future release.

Hints For Emacs 19 Users
************************

   This package is tested with the GNU Emacs 19.34. The Emacs 19.34 has
had not all features of the XEmacs. Therefore also some of the features
of this package could not be implemeted in the Emacs 19.

   Please read also the Emacs 19 related file `README-EMACS-19'!

   The following is a list of missing features:

   * The capability to start an action from the help buffer. This is
     only possible in the XEmacs, because in the Emacs 19.34 one can't
     assign keymaps to a text region (overlay).

   * The keybindings of the drag and drop commands are not displayed in
     the menus, because the Emacs 19 isn't able to handle the following
     menu specification: `:keys "\\[idd-help-mouse-drag-and-drop]"'.

   * The function `file-remote-p' couldn't be implemeted, because of the
     lack of the function `ange-ftp-ftp-p' in the ange-ftp package of
     the Emacs 19.34.

   * The history variable determined by `tmpl-history-variable-name'
     isn't used, because the function `read-file-name' doesn't support
     it in the Emacs 19.

   * The mouse pointer shape (glyph) wont be changed in the Emacs 19
     during a drag and drop command. For that a way is needed to set
     the mouse pointer shape to an image.

Bug Reports
***********

   There's no software out there without bugs. This package contains
software, therefore it has bugs. I (Heiko Münkel
<muenkel@tnt.uni-hannover.de>) have inserted most of the bugs in this
package by myself, but I've forgotten where. So please help me out of
this disaster and send bug reports, if you've found one of these little
animals. I'll try to do my very best to fix them and to insert new ones.

   If it's possible, you should use the command

             M-x hm--html-submit-bug-report

   There's also an entry in the pulldown menu for this.

   In some cases a backtrace would also be appropriate.

   If you can't send the report with this function, at least include
the package version and your `Emacs'/`XEmacs' version.

   In the best of all worlds you would also include a patch to fix the
bug.

   *Note*: It's not true that I've inserted the bugs as a marketing
trick, so that you must buy the next version to get some of them fixed.
This is false, because this software is free.